react-jss

What is react-jss?

react-jss is a library that allows you to use JSS (JavaScript Style Sheets) with React. It provides a way to style React components using JavaScript objects, enabling dynamic styling and theming capabilities.

What are react-jss's main functionalities?

Basic Styling

This feature allows you to define styles using JavaScript objects and apply them to React components. The `createUseStyles` function is used to create a hook that generates the necessary CSS classes.

const useStyles = createUseStyles({
  button: {
    background: 'blue',
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    cursor: 'pointer'
  }
});

function MyButton() {
  const classes = useStyles();
  return <button className={classes.button}>Click Me</button>;
}

Theming

Theming allows you to define a theme object and use it to style your components. This makes it easy to apply consistent styling across your application and switch themes dynamically.

const theme = {
  primaryColor: 'blue',
  secondaryColor: 'green'
};

const useStyles = createUseStyles({
  button: {
    background: ({ theme }) => theme.primaryColor,
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    cursor: 'pointer'
  }
});

function MyButton() {
  const classes = useStyles({ theme });
  return <button className={classes.button}>Click Me</button>;
}

Dynamic Styling

Dynamic styling allows you to change styles based on component props or state. This example shows how to change the button's background color based on the `isPrimary` prop.

const useStyles = createUseStyles({
  button: {
    background: ({ isPrimary }) => (isPrimary ? 'blue' : 'gray'),
    color: 'white',
    padding: '10px 20px',
    border: 'none',
    borderRadius: '5px',
    cursor: 'pointer'
  }
});

function MyButton({ isPrimary }) {
  const classes = useStyles({ isPrimary });
  return <button className={classes.button}>Click Me</button>;
}

Other packages similar to react-jss

styled-components

styled-components is a library for styling React components using tagged template literals. It allows you to write actual CSS code to style your components and supports theming and dynamic styling. Compared to react-jss, styled-components uses a different syntax and approach but offers similar capabilities.

emotion

emotion is a library designed for writing CSS styles with JavaScript. It provides both a CSS-in-JS solution and a styled-components-like API. Emotion is known for its performance and flexibility, making it a strong alternative to react-jss.

aphrodite

aphrodite is a library for styling React components using JavaScript objects. It focuses on performance and ease of use, similar to react-jss. Aphrodite generates atomic CSS classes to minimize style recalculations and reflows.

README

React integration of JSS

React-JSS provides components for JSS as a layer of abstraction. JSS and presets are already built in! Try it out on webpackbin.

The benefits are:

• Theming support out of the box.
• Lazy evaluation - sheet is created only when component will mount.
• Auto attach/detach - sheet will be rendered to the DOM when component is about to mount and will be removed when no element needs it.
• A Style Sheet gets shared between all elements.

Table of Contents

• Install
• Usage
  • Basic
  • Theming
  • Server-side rendering
  • Reuse styles in different components
  • The classNames helper
  • The inner component
  • Custom setup
  • Decorators
• Contributing
• License

Install

npm install --save react-jss

Usage

React-JSS wraps your component with an higher-order component. It injects classes and sheet into props, where sheet is a JSS StyleSheet instance. It can act both as a simple wrapping function and as a ES7 decorator

JSS class names are scoped by default, you will need to reach into props.classes to get the generated class names.

Example

Try it out on webpackbin.

import React from 'react'
import injectSheet from 'react-jss'

const styles = {
  button: {
    background: props => props.color
  },
  label: {
    fontWeight: 'bold'
  }
}

const Button = ({classes, children}) => (
  <button className={classes.button}>
    <span className={classes.label}>
      {children}
    </span>
  </button>
)

export default injectSheet(styles)(Button)

Theming

The idea is that you define theme, wrap your application with ThemeProvider and pass the theme to ThemeProvider. ThemeProvider will pass it over context to your styles creator function and to your props. After that you may change your theme, and all your components will get new theme automatically.

Under the hood react-jss uses unified CSSinJS theming solution for React. You can find detailed docs in its repo.

Using ThemeProvider:

• It has theme prop which should be an object or function:
  • If it is an Object and used in a root ThemeProvider then it's intact and being passed down the react tree.
  • If it is Object and used in a nested ThemeProvider then it's being merged with theme from a parent ThemeProvider and passed down the react tree.
  • If it is Function and used in a nested ThemeProvider then it's being applied to the theme from a parent ThemeProvider. If result is an Object it will be passed down the react tree, throws otherwise.
• ThemeProvider as every other component can render only single child, because it uses React.Children.only in render and throws otherwise.
• Read more about ThemeProvider in theming's documentation.

import React from 'react'
import injectSheet, {ThemeProvider} from 'react-jss'

const Button = ({classes, children}) => (
  <button className={classes.button}>
    <span className={classes.label}>
      {children}
    </span>
  </button>
)

const styles = theme => ({
  button: {
    background: theme.colorPrimary
  },
  label: {
    fontWeight: 'bold'
  }
})

const StyledButton = injectSheet(styles)(Button)

const theme = {
  colorPrimary: 'green'
}

const App = () => (
  <ThemeProvider theme={theme}>
    <StyledButton>I am a button with green background</StyledButton>
  </ThemeProvider>
)

In case you need to access the theme but not render any CSS, you can also use withTheme. It is a Higher-order Component factory which takes a React.Component and maps the theme object from context to props. Read more about withTheme in theming's documentation.

import React from 'react'
import injectSheet, {withTheme} from 'react-jss'

const Button = withTheme(({theme}) => (
  <button>I can access {theme.colorPrimary}</button>
))

Namespaced themes can be used so that a set of UI components should not conflict with another set of UI components from a different library using also react-jss.

import {createTheming} from 'react-jss'

// Creating a namespaced theming object.
const theming = createTheming('__MY_NAMESPACED_THEME__')

const {ThemeProvider: MyThemeProvider} = theming

const styles = theme => ({
  button: {
    background: theme.colorPrimary
  }
})

const theme = {
  colorPrimary: 'green'
}

const Button = ({classes, children}) => (
  <button className={classes.button}>
    {children}
  </button>
)

// Passing namespaced theming object inside injectSheet options.
const StyledButton = injectSheet(styles, { theming })(Button)

// Using namespaced ThemeProviders - they can be nested in any order
const App = () => (
  <OtherLibraryThemeProvider theme={otherLibraryTheme}>
    <OtherLibraryComponent />
    <MyThemeProvider theme={theme}>
      <StyledButton>Green Button</StyledButton>
    </MyThemeProvider>
  <OtherLibraryThemeProvider>
)

Server-side rendering

After the application is mounted, you should remove the style tag used critical CSS rendered server-side.

import {renderToString} from 'react-dom/server'
import {JssProvider, SheetsRegistry} from 'react-jss'
import MyApp from './MyApp'

export default function render(req, res) {
  const sheets = new SheetsRegistry()

  const body = renderToString(
    <JssProvider registry={sheets}>
      <MyApp />
    </JssProvider>
  )

  // Any instances of `injectSheet` within `<MyApp />` will have gotten sheets
  // from `context` and added their Style Sheets to it by now.

  return res.send(renderToString(
    <html>
      <head>
        <style type="text/css">
          {sheets.toString()}
        </style>
      </head>
      <body>
        {body}
      </body>
    </html>
  ))
}

Reuse styles in different components

In order to reuse the same styles and the same generated style sheet between 2 entirely different and unrelated components, we suggest to extract a renderer component into a separate one and reuse it.

const styles = {
  button: {
    color: 'red'
  }
}
const RedButton = injectSheet(styles)(({classes, children}) => (
  <button className={classes.button}>{children}</button>
))

const SomeComponent1 = () => (
  <div>
    <RedButton>My red button 1</RedButton>
  </div>
)

const SomeComponent2 = () => (
  <div>
    <RedButton>My red button 2</RedButton>
  </div>
)

Alternatively you can create own Style Sheet and use the composes feature. Also you can mix in a common styles object, but take into account that it grow the overall CSS size.

The classNames helper

You can use classNames together with JSS same way you do it with global CSS.

import classNames from 'classnames'

const Component = ({classes, children, isActive}) => (
  <div
    className={classNames({
      [classes.normal]: true,
      [classes.active]: isActive
    })}>
    {children}
  </div>
)

The inner component

const InnerComponent = () => null
const StyledComponent = injectSheet(styles, InnerComponent)
console.log(StyledComponent.InnerComponent) // Prints out the inner component.

Custom setup

If you want to specify a JSS version and plugins to use, you should create your own Jss instance, setup plugins and pass it to JssProvider.

import {create as createJss} from 'jss'
import {JssProvider} from 'react-jss'
import vendorPrefixer from 'jss-vendor-prefixer'

const jss = createJss()
jss.use(vendorPrefixer())

const Component = () => (
  <JssProvider jss={jss}>
    <App />
  </JssProvider>
)

You can also access the Jss instance being used by default.

import {jss} from 'react-jss'

Multi-tree setup

In case you render multiple react rendering trees in one application, you will get class name collisions, because every JssProvider rerender will reset the class names generator. If you want to avoid this, you can share the class names generator between multiple JssProvider instances.

Note: in case of SSR, make sure to create a new generator for each request. Otherwise class names will become indeterministic and at some point you may run out of max safe integer numbers.

import {createGenerateClassName, JssProvider} from 'react-jss'

const generateClassName = createGenerateClassName()

const Component = () => (
  <div>
    <JssProvider generateClassName={generateClassName}>
      <App1 />
    </JssProvider>
    <JssProvider generateClassName={generateClassName}>
      <App2 />
    </JssProvider>
  </div>
)

Decorators

Beware that decorators are stage-2 proposal, so there are no guarantees that decorators will make its way into language specification. Do not use it in production. Use it at your own risk and only if you know what you are doing.

You will need babel-plugin-transform-decorators-legacy.

import React, {Component} from 'react'
import injectSheet from 'react-jss'

const styles = {
  button: {
    backgroundColor: 'yellow'
  },
  label: {
    fontWeight: 'bold'
  }
}

@injectSheet(styles)
export default class Button extends Component {
  render() {
    const {classes, children} = this.props
    return (
      <button className={classes.button}>
        <span className={classes.label}>
          {children}
        </span>
      </button>
    )
  }
}

Contributing

See our contribution guidelines.

License

MIT